Repository navigation
fix(core): explicit saturating narrowing, const decoders, complete API docs, and a rustdoc gate - #1
Conversation
The decoder is `forbid(unsafe_code)` and never panics, so the interesting failure mode is not a crash but a wrong value. This hardens every place where a wider integer was narrowed with an unchecked `as`. - The two CAS-latency derivations (the linter's supported-set check and the vendor-profile rated CL) narrowed a `u32` quotient to `u16`. Safe for decoded bytes, but fragile and non-obvious; they now narrow explicitly and saturate, so a hand-built out-of-range value cannot wrap into a plausible-looking latency. Regression tests cover both, including the case that wrapped to a silent `CL5`. - The supported-CAS mask arithmetic now computes its bit index in one integer domain, with a compile-time check tying the bit count to the byte count it derives from. - The reference-raw-card `Display` no longer casts the alphabet length or array indices. Also, since the crate is `no_std` and meant to be embeddable, every pure decoder and accessor it can is now `const fn`, and two `pub(crate)` markers that were redundant inside private modules became plain `pub` (same effective visibility). Documentation is completed in the same pass: an `# Errors` section on every public `Result`-returning function, identifiers in prose wrapped in backticks, and bit-range notation escaped so it no longer parses as an intra-doc link. No decoded output changes: the golden snapshots pass byte for byte.
…z blocker The gate gains a rustdoc step, because doc breakage was invisible to it: bit-range notation in field docs (`bits [7:5]`) parsed as intra-doc links, so every rendered field doc was a broken link, and one public doc pointed at a private item. Both are now fixed and cannot regress silently. A curated set of `clippy::pedantic` lints moves to `deny` at the workspace level, covering exactly the classes this pass found: silent narrowing, missing `# Errors`, unbackticked identifiers, `&Option<T>` arguments, and needless pass-by-value. It stays curated rather than blanket so a future upstream lint cannot break CI on a toolchain bump. `ref_option` postdates the MSRV; plain `rustc` ignores `clippy::*` names entirely, so MSRV builds are unaffected. The fuzz harness documentation claimed the fuzz crate "cannot link" on Windows MSVC. That was wrong, and now says what is actually true: it compiles and links, and the resulting binary fails to load on its `clang_rt.asan_dynamic-x86_64.dll` import (exit `STATUS_DLL_NOT_FOUND`, then `STATUS_ENTRYPOINT_NOT_FOUND` with LLVM's runtime on `PATH`, and LNK1120 with `CC=clang CXX=clang++`). The attempt is recorded in the phase ledger rather than left as a silently blank row, and `spdr/fuzz/Cargo.lock` is committed so the harness resolves reproducibly. The README still says "property-tested, not fuzzed", which remains the honest state: the deep run is still owed on a Linux or WSL host.
mertefesensoy
left a comment
There was a problem hiding this comment.
Thanks for this, @danalec. The code side is solid: the saturation guards are correct, the rustdoc gate closes a real gap, and the README's "property-tested, not fuzzed" line is left honest. What needs another pass is the prose. In this repo the accuracy of every public claim is the bar, and several statements in the CHANGELOG and the lint-table comment don't hold up against the diff or against a run. No blockers; one major, four minor, five nits.
What I verified
On the PR head (663a30f), Windows, stable 1.96:
cargo build -p spdr(no_std guard),cargo fmt --check,cargo clippy --workspace --all-targets -- -D warnings: clean.- Same clippy with
-W clippy::pedantic: zero warnings. RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --lib: clean.cargo test --workspace: 110 passed, 0 failed.- MSRV (rustc 1.85.1):
cargo build -p spdr,cargo clippy --workspace --all-targets -- -D warnings, andcargo test --workspace(110 passed) all clean. The 31 newconst fns are fine on the MSRV.
On the base (6b0d2d5), for comparison:
cargo docemits 22 warnings: 21unresolved link to 7:5-style, plus the privaterun_lintlink. So the new gate is needed.- I copied the three new tests into the base tree and ran them there.
lint::cas_latency_saturates_instead_of_wrappingandvendor::rated_cas_latency_saturates_instead_of_wrappingfail (wrappedCL5). Theu32::MAXrounding case panics on the add overflow.timing::cas_latency_bit_domain_covers_exactly_the_maskpasses.
Major
M1 · The CHANGELOG and the lint-table comment make claims the diff does not support. The CHANGELOG ships with the next crates.io release, so each of these needs correcting before merge:
CHANGELOG.md:18· "29 pure decoders and accessors markedconst fn". The diff addsconstto 31 functions: 27 inspdrand 4 inspdr-cli. Neither count is 29.CHANGELOG.md:18-19· "so a constant SPD byte can be decoded at compile time". Every field decoder that becameconstis crate-internal. None of the publicdecode_*entry points isconst. A downstream user still can't decode anything at compile time.CHANGELOG.md:9and the PR description · "No public API change".constis now on five publicspdritems (Finding::severity,Finding::code,SpdImage::is_empty,CasLatencies::contains,Timings::base_data_rate_mt_s) and onspdr_cli::DecodeResults::all_decoded. The change is additive and I'm fine with it, but removingconstlater is breaking. This is a semver commitment, so list it as an API addition, not as "no change".CHANGELOG.md:15· "each was confirmed to fail against the previousascast". The two saturation tests do. The bit-domain test does not, and can't: the base arithmetic was already correct. It is a characterization test, which is still worth having. Say that.CHANGELOG.md:33· "every rendered field doc was a broken link". Not on the base. Rustdoc warned 21 times about bit ranges, but the rendered HTML showsbits [7:5]as plain text with no link. The real defect was the warnings, which the new-D warningsgate would trip on. The rendered output was fine.Cargo.toml:25-27· "ref_optionpostdates the 1.85 MSRV ... only clippy runs on pre-1.87 toolchains warn". Clippy's own changelog movesref_optionintopedanticin Rust 1.83 (released 2024-11-28), before the MSRV. It also checks out empirically: clippy 1.85 runs this workspace under-D warningswith nounknown_lintswarning. The PR description repeats this as "verified, not assumed". Please correct or drop the sentence in both places.Cargo.toml:21· "each of these caught a real issue".bool_to_int_with_ifis a style lint. The only change it drove is the exit-code rewrite (see N2). Either drop it from the list or soften the comment.
Minor
m1 · Documentation trail.
docs/numerical-claims.mdsays every number in the docs is logged there with its source. This PR adds several numbers and logs none of them: the 29 (31) count, "3 passed in 1.17 s",PROPTEST_CASES=100000,-max_total_time=45, and the two exit codes.- Every prior change has its own
docs/implementations/YYYY-MM-DD-<slug>.md. This one needs one too: a CI gate, a workspace lint policy, and a numeric-behaviour change are each meaningful. Most of the content is already in the PR description.
m2 · Phase 6 report edits (docs/implementations/2026-06-05-phase-6-robustness.md).
- Lines 129-130 repeat a sentence: "proptest is pure Rust and runs anywhere
cargo testdoes." appears twice. - Line 176 says "see the measured details in Design Decisions". Design Decisions (line 132) only says "measured above", and the details are actually in Problem / Motivation (line 28).
- The deep-run ledger is the right place for the attempted run, and logging it beats leaving the row blank. The row should say who ran it and on which host, though, because "this machine" in that report means the maintainer's box.
- The dated June rationale is rewritten in place. A dated addendum would preserve what the report said when it was written.
m3 · pub(crate) to pub (spdr/src/identity.rs:400, spdr/src/timing.rs:291). Effective visibility is unchanged today. Before, though, the compiler enforced the boundary; now a comment does. A future pub use identity::* or a module made pub would silently export these helpers. None of the denied lints requires the change, so please revert to pub(crate). const can stay.
m4 · Em dashes at CHANGELOG.md:19 and spdr/src/timing.rs:220. The repo uses the middle dot (·) or plain punctuation as its separator and has no em or en dashes anywhere in the shipped tree. To be fair, that convention isn't written down anywhere in the repo yet, so you had no way to know.
Nits
- N1
spdr/src/vendor.rs:507·saturating_addkeeps the add from overflowing, but nearu32::MAXit rounds down. For example,taa = u32::MAXwithtck = 2^31gives 1 instead of 2. Widening tou64for the add and divide makes the rounding exact, and only the final narrowing needs to saturate. This is unreachable from decoded bytes, so it's a nit. - N2
spdr-cli/src/lib.rs:162·i32::from(!results.all_decoded())reads worse thanif results.all_decoded() { 0 } else { 1 }for an exit code. Consider droppingbool_to_int_with_iffrom the deny list, or an#[allow]at this site. - N3
.github/workflows/ci.yml:31· missing# Errorssections are caught by the Clippy step (missing_errors_doc), not by rustdoc. The comment conflates the two. - N4
CHANGELOG.md:15· "the silent-narrowing fix above". The fix is listed below, under Fixed. - N5 The
\[7:5\]escapes are correct, but they make the source harder to read in a crate whose source is meant to be the open reference. A code span (`[7:5]`) or "bits 7:5" also silences rustdoc and reads cleanly.
No need to split the PR. It's reviewable as one, and the fixes above are all prose apart from m3 and N1.
… claims
The review asked for prose corrections, three code changes, and a
documentation trail. All of it is in this commit.
Code:
- `vendor::rated_cas_latency` computes the round-to-nearest in `u64`, so the
rounding stays exact across the whole `u32` input range instead of
saturating the add and rounding down. Only the final narrowing to `u16`
saturates. New test: `rated_cas_latency_rounds_in_u64`.
- `identity::decode_module_type` and `timing::data_rate_mt_s` go back to
`pub(crate)`. The pass had widened them to `pub`, which left the boundary to
a comment instead of the compiler. `const` is kept.
- The CLI exit code is `if results.all_decoded() { 0 } else { 1 }` again.
`bool_to_int_with_if` is dropped from the workspace deny list: it is a style
lint that forbids the branch form and asks for `i32::from(!ok)`, so its only
effect here was to force the less readable expression.
Claims corrected, each against a measurement recorded in
`docs/numerical-claims.md`:
- 31 functions became `const fn` (27 in `spdr`, 4 in `spdr-cli`), and every
one of them is crate-internal or an accessor: no public `decode_*` entry
point is `const`.
- Six public items gained `const`, so the change is additive rather than "no
public API change".
- The two saturation tests were confirmed to fail against the previous `as`
cast; the bit-domain test is a characterization test, since the base
arithmetic was already correct.
- The rendered documentation was never broken: on the base `6b0d2d5` the
bit-range text is plain text and no occurrence is wrapped in an `<a>`
element. The defect was the 22 rustdoc warnings, which the new `-D warnings`
gate turns into a build failure.
- `ref_option` is not newer than the MSRV: clippy 1.85.1 reports it as implied
by `clippy::pedantic`.
Trails:
- `docs/numerical-claims.md` records every number above with its source.
- `docs/implementations/2026-10-25-narrowing-const-and-doc-gates.md` is the
dated note for this change.
- The Phase 6 report keeps its dated June rationale and gains a dated
addendum for the measured Windows fuzz failure mode, instead of the
rationale being rewritten in place.
No decoded output changes. `cargo fmt --check`, `cargo clippy --workspace
--all-targets -- -D warnings`, `RUSTDOCFLAGS="-D warnings" cargo doc
--workspace --no-deps --lib`, `cargo build -p spdr` and `cargo test
--workspace` are all clean.
|
Thanks for the review. Every point is addressed in Code (3 changes)
M1 - the seven claims, corrected
Minor and nits
Checks
|
The dated implementation note listed `bool_to_int_with_if` among the denied workspace lints even though `Cargo.toml` dropped it in the same pass, and its verification section kept the "zero warnings" result from the pre-review head instead of re-running after the exit code returned to the branch form. Both claims are now corrected against measurements recorded in `docs/numerical-claims.md`. `CHANGELOG.md` no longer claims `cargo doc` warned on every bit-range field; it states the measured count, which is traced in the same file. The PR description is updated separately to match the corrected claims.
|
Head is now
Re-verified on Windows and Linux: A maintainer still needs to approve the CI run for this head (it is |
mertefesensoy
left a comment
There was a problem hiding this comment.
Approving. Every point from my review is answered in fd92f40 and c949eb0, and CI passed at c949eb07 (run).
- The CHANGELOG now matches the diff: 31
const fn(CHANGELOG.md:25), the six publicconstitems listed as an API addition (:16-18), and the bit-domain test described as a characterization test (:23). rated_cas_latencyrounds inu64(spdr/src/vendor.rs:509-510, test at:591), and both helpers are back topub(crate)(spdr/src/identity.rs:400,spdr/src/timing.rs:290).- I pushed one commit on top that turns the two em dashes left in
docs/numerical-claims.md(lines 239 and 240) into commas, so the docs keep the repo's no-dash convention.
Thanks for the careful follow-up, and for tracing every new number in docs/numerical-claims.md.
AI-assisted with Claude Code.
|
Your patch is live in 1.1.2 @danalec. Thank you for your contribution 😋 |
Summary
A behaviour-preserving quality pass over the shipped surface. The public API
gains
conston six accessors, which is additive and therefore a semvercommitment: removing it later would be breaking. No decoded output changes for
real SPD bytes — every golden snapshot passes byte for byte. The only behaviour
change is for hand-built, out-of-range values, which now saturate or round
exactly instead of wrapping.
This is opened from a fork. The branch carries the quality pass and the
corrections requested in review, on top of
main.The bug class worth reviewing first
The core is
forbid(unsafe_code)and never panics, so its interesting failuremode is not a crash but a wrong value. Every place where a wider integer was
narrowed with an unchecked
aswas hardened:spdr/src/lint.rs)and the vendor-profile rated CL (
spdr/src/vendor.rs) — narrowed au32quotient to
u16. Safe for decoded bytes, since both fields are 16-bit, butfragile and not evident from the code. They now narrow explicitly and
saturate, so a hand-built out-of-range value cannot wrap. Each has a
regression test, including the case that wrapped to a silent
CL5— aplausible-looking latency that would have been reported as real.
u64, so it staysexact across the whole
u32input range; only the final narrowing saturates.spdr/src/timing.rs) now computes its bitindex in a single integer domain, with a compile-time assertion tying the bit
count to the byte count it derives from.
Display(spdr/src/module.rs) no longer casts thealphabet length or array indices.
Gate gaps this closes
cargo docwas not run anywhere, so doc breakage was invisible. Bit-rangenotation in field docs (
bits [7:5]) parsed as intra-doc links and produced 21unresolved-link warnings on the base, plus one public doc link to a private
item — 22 warnings in total. The rendered documentation was correct: the
bit-range text appeared as plain text, not a link. The defect was the warnings,
so CI now builds rustdoc with
-D warningsand fails on them.A curated set of
clippy::pedanticlints isdeny-ed at the workspace level,covering exactly the classes this pass found: silent narrowing, missing
# Errorssections, unbackticked identifiers,&Option<T>arguments, andneedless pass-by-value. It is curated rather than blanket so that a future
upstream lint cannot break CI on a toolchain bump.
ref_optionis resolved byclippy on the MSRV toolchain (it is implied by
clippy::pedantic), so MSRVbuilds are unaffected — measured, not assumed.
bool_to_int_with_ifwas droppedfrom the set: it is a style lint whose only effect here was to force a less
readable exit code.
Also included
const fn(31 functions:27 in
spdr, 4 inspdr-cli), which is the point of an embeddableno_stdcrate. No public
decode_*entry point isconst, so a downstream userstill cannot decode an SPD image at compile time.
# Errorssections on every publicResult-returning function; identifiersin prose wrapped in backticks; bit-range notation as code spans (
[7:5]),which rustdoc does not link and which read cleanly.
documented as unable to link on Windows MSVC. That is wrong:
cargo fuzz build decode_alldoes compile and link, and the binary then fails to load on itsclang_rt.asan_dynamic-x86_64.dllimport (STATUS_DLL_NOT_FOUND;STATUS_ENTRYPOINT_NOT_FOUNDwith LLVM's runtime onPATH; LNK1120 withCC=clang CXX=clang++). The measured failure mode is now recorded inspdr/fuzz/Cargo.tomland the phase-6 report, and the attempt is logged inthe deep-run ledger instead of sitting as a silently blank row.
spdr/fuzz/Cargo.lockis committed, so the harness resolves reproduciblylike the parent workspace already does.
docs/numerical-claims.md, and thedated note is
docs/implementations/2026-10-25-narrowing-const-and-doc-gates.md.On the "fuzzed" claim
The README wording is deliberately unchanged: it still says property-tested,
not fuzzed. The deep run is still owed on a Linux or WSL host; on Windows the
harness never reached a single execution. The on-box substitute noted in the
ledger is
PROPTEST_CASES=100000 cargo test --release --test robustness, whichis property-testing, not fuzzing.
How this was checked
cargo fmt --check,cargo clippy --workspace --all-targets -- -D warnings,RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --lib,cargo build -p spdr(the existingno_stdguard), andcargo test --workspaceare all clean on Windows and on Linux, full suite passing. Withblanket
-W clippy::pedanticthere is one warning,bool_to_int_with_ifonthe restored
if ok { 0 } else { 1 }exit code: the lint is not in the denyset and the CI gate does not enable blanket
pedantic, so the gate staysclean. The two saturation tests were confirmed to fail against the previous
ascast before being kept; the bit-domain test is a characterization test,since the base arithmetic was already correct.
Workflow runs from this fork require a maintainer's approval because the change
set touches
.github/workflows/ci.yml; approving one runs the same steps onubuntu-latest.